# Claude Code 源码学习手册

> 基于 2026-03-31 通过 npm source map 泄露的 Claude Code 源码快照。
> 语言: TypeScript | 运行时: Bun | 终端 UI: React + Ink
> 规模: ~1,900 文件, 512,000+ 行代码

---

## 阅读顺序

本手册按**由浅入深**的顺序组织，建议依次阅读 01-12 章掌握核心架构，再通过 13-21 章深入 Prompt 体系：

| 序号 | 文档 | 内容 | 难度 |
|------|------|------|------|
| 01 | [[01 - 项目概览]] | 项目是什么、做什么、目录结构 | 入门 |
| 02 | [[02 - 技术栈与架构总览]] | 技术选型、整体架构图、数据流 | 入门 |
| 03 | [[03 - 启动流程]] | 从命令行输入 `claude` 到 UI 渲染的完整过程 | 基础 |
| 04 | [[04 - Tool 系统]] | 核心机制：Tool 接口定义、注册、调度 | 核心 |
| 05 | [[05 - 权限系统]] | 安全核心：权限检查、模式、规则匹配 | 核心 |
| 06 | [[06 - Query 引擎与对话循环]] | LLM 交互：消息构建、API 调用、流式处理 | 核心 |
| 07 | [[07 - 命令系统]] | 斜杠命令的定义、加载、三种类型 | 进阶 |
| 08 | [[08 - 服务层]] | API、MCP、OAuth、LSP 等外部集成 | 进阶 |
| 09 | [[09 - UI 渲染系统]] | React 如何渲染到终端 | 进阶 |
| 10 | [[10 - 多 Agent 与协调器]] | 子 Agent、协调器模式、Agent Swarms | 高级 |
| 11 | [[11 - 配置与内存系统]] | 设置层级、CLAUDE.md、持久化记忆 | 高级 |
| 12 | [[12 - 关键设计模式]] | 贯穿项目的设计思想与模式总结 | 总结 |

### Prompt 体系深度分析（新增）

| 序号 | 文档 | 内容 | 难度 |
|------|------|------|------|
| 13 | [[13 - Prompt 体系总览]] | 六大 Prompt 子系统导航与核心架构图 | 导读 |
| 14 | [[14 - System Prompt 架构]] | 20+ Section 模块化组装 + 条件注入逻辑 | 核心 |
| 15 | [[15 - Agent 与 SubAgent Prompt]] | 6 种 Agent 类型 + 工具权限矩阵 | 核心 |
| 16 | [[16 - Prompt Caching 与 Context 管理]] | 三级缓存策略 + Auto-Compact + 锁存模式 | 高级 |
| 17 | [[17 - 权限系统与 Safety Prompt]] | 10 层纵深防御 + AI 分类器 | 高级 |
| 18 | [[18 - Memory 与 Hooks 系统]] | 6 层 Memory + 26 种 Hook + 配置注入 | 高级 |
| 19 | [[19 - Prompt 工程技巧与设计模式]] | 12 个值得学习的 Prompt 设计模式 | 精华 |
| 20 | [[20 - Tool 系统 Prompt 详解]] | 39+ 工具的完整 Prompt 分析与设计模式 | 核心 |
| 21 | [[21 - 用户输入处理与消息格式化]] | 输入到 API 完整链路 + Skill 系统 | 进阶 |

---

## 核心文件速查

| 文件 | 作用 |
|------|------|
| `src/entrypoints/cli.tsx` | 最外层入口，快速路径分发与动态加载 |
| `src/entrypoints/init.ts` | 全局初始化（配置、TLS、预连接、清理回调） |
| `src/main.tsx` | CLI 入口，Commander.js 命令解析 |
| `src/Tool.ts` | Tool 类型定义（接口规范） |
| `src/tools.ts` | Tool 注册表（所有 Tool 的集合） |
| `src/query.ts` | 单轮对话执行器（API 调用 + Tool 调度） |
| `src/QueryEngine.ts` | 会话级引擎（多轮管理、上下文构建） |
| `src/commands.ts` | 命令注册表 |
| `src/context.ts` | 系统/用户上下文收集 |
| `src/cost-tracker.ts` | Token 费用追踪 |
| `src/state/AppState.ts` | 全局应用状态定义 |

---

## 术语表

| 术语 | 含义 |
|------|------|
| **Tool** | Claude 可调用的能力单元（如 Bash、FileRead） |
| **Command** | 用户输入的斜杠命令（如 /commit、/compact） |
| **MCP** | Model Context Protocol，外部工具集成协议 |
| **LSP** | Language Server Protocol，语言服务器协议 |
| **Bridge** | IDE（VS Code / JetBrains）与 CLI 的通信层 |
| **Coordinator** | 多 Agent 协调器模式 |
| **Worktree** | Git 工作树隔离模式 |
| **Permission Mode** | 权限模式：default / plan / auto / bypassPermissions |
| **Feature Flag** | 通过 `bun:bundle` 的 `feature()` 实现编译时特性开关 |
| **Ink** | 项目自定义的 React 终端渲染器 |